home *** CD-ROM | disk | FTP | other *** search
/ Aminet 3 / Aminet 3 - July 1994.iso / Aminet / dev / gui / intuigen2.lzh / IntuiGen / doc / IntuiGen.txt < prev   
Encoding:
Text File  |  1993-12-22  |  66.1 KB  |  1,341 lines

  1. IntuiGen.txt doc
  2.  
  3. (C) Copyright 1993 Justin Miller, P.O. Box 17, Imbler, OR  97841.
  4.       This file may be freely distributed with IntuiGen 2.0.
  5.       All Other Rights Reserved.
  6.       The Author makes no warranties, express or implied, as to
  7.     the accuracy or suitability of the material contained herein.
  8.  
  9.  
  10. IntuiGen is (C) Copyright 1993 Justin Miller.  It is being offered as
  11. Shareware.  If you make use of this program or its included libraries,
  12. please send a check or money order for $15 payable to Justin Miller.
  13. Note that if you want to distribute programs which make use of
  14. the GTRequest or IGRequest libraries, you must register!
  15. For a complete licensing agreement for IntuiGen and its accompanying source,
  16. documentation, and example files, see COPYRIGHT.txt included in this archive.
  17.  
  18. The IntuiGen package is freely distributable, providing all the files are
  19. included, and no unreasonably large distribution fees are charged.  For
  20. details, see COPYRIGHT.txt.
  21.  
  22. Email comments, suggestions, and bug reports to:  jcmiller@mit.edu
  23. If you don't have access to the internet, you can mail me at the
  24. above US Mail address also.
  25.  
  26.  
  27. Objects
  28. An object is any visual user interface element that you place in the Object
  29. Window. Objects are created with tools in the ToolBox, and may be moved
  30. freely, deleted, and depending on the type of object, assigned a keyboard
  31. command, linked to a structure field, or linked to a user-defined function.
  32. Examples of Objects include Boolean Gadgets, CheckBox_Kind controls,
  33. ListView_Kind controls, and Images.
  34.  
  35.  
  36. Object Window
  37. The Object Window is the window in which Objects you create with the tools
  38. from the ToolBox appear.  Its title is "Object Window."  Code is generated
  39. (at your option) for this window and everything in it.
  40.  
  41.  
  42. ToolBox
  43. The ToolBox is the small window that appears in the upper right corner of
  44. the screen.  Its title is "Tools."  It contains the tools that you can use
  45. to create Objects to be placed in the Object Window.
  46.  
  47.  
  48. Clips Window
  49. The Clips Window is a small window that appears in the lower left corner of
  50. the screen.  You can place objects in this window to get them out of the
  51. way, or to save them for later use.  No code is generated for the Clips
  52. Window or any object in it. When an Object is deleted from the Object
  53. Window, it appears in the Clips Window. When it is deleted from the Clips
  54. Window, it is deleted permanently.  At any time you may move an object from
  55. the Clips Window to the Object Window using the standard technique for
  56. moving Objects.
  57.  
  58.  
  59. PseudoKinds
  60. A Pseudokind is a type of User Interface element (Object) that can be used
  61. under GTRequest, but is not a real GadTools kind; instead GTRequest makes
  62. this kind appear to the programmer as if it were a GadTools kind.
  63. Pseudokinds include:
  64.  
  65.             ToggleSelect Pseudokind
  66.             ImageButton Pseudokind
  67.             EditList Pseudokind
  68.  
  69.  
  70.  
  71. GTControl
  72. A GTControl is a User Interface element that is displayed and used by
  73. GTRequest.  GTControls are usually based on GadTools kinds, although they
  74. may also be based on Pseudokinds.  A GTControl is represented in memory by
  75. a GTControl structure, and also requires a NewGadget structure, a TagList,
  76. and optionally one or more MessageHandlers.
  77.  
  78.  
  79. MessageHandlers
  80. A Message Handler is a structure that contains information about how to
  81. handle a certain message reaching a GTControl or a GTRequest.  Message
  82. Handlers exist in a linked list, and are attached to the Object
  83. (GTControl or GTRequest) that they are to handle the message for.  They
  84. contain information on the message type, a pointer to a function to call to
  85. verify that a message is of this type (not required for standard message
  86. types), and a pointer to a function to call if a message is indeed of the
  87. required type (this function is usually user-defined).  The MessageHandler
  88. structure is the interface that links events in a requester to user-defined
  89. code.
  90.  
  91.  
  92. Button_Kind
  93. Can be generated under 1.2 or above.
  94.  
  95. Can run under Intuition or GadTools
  96.  
  97. To create a Button_Kind, Boolean Gadget (pre-2.0), or a Toggleselect Gadget
  98. (pre-2.0 or a "ToggleSelect" pseudokind), use the Button Tool.  The button
  99. tool is the tool in the upper left corner of the Tools Window.    Its
  100. keyboard equivalent is "b." You then must specify a structure name for this
  101. button in the Struct Name field, and GadgetText for the button in the Text
  102. field.    Default width and height values will be selected for you, but you
  103. may override them in the Width and Height fields.  You can also assign a
  104. GadgetID, and control the color registers used for the GadgetText, left and
  105. top sides of the border, and bottom and right sides of the border using the
  106. Text Color, Border1 Color, and Border2 Color field respectively. To create
  107. a Toggleselect gadget, click on the ToggleSelect button in the bank of
  108. Toggle buttons in the lower left of the requester.  You can also specify
  109. other Gadget flags using similarly named buttons in this bank of Toggle
  110. buttons.  Under GadTools and GTRequest, all buttons and ToggleSelects are
  111. GadgHComp buttons.  Under IGRequest, or Intuition (not GadTools), by
  112. default, the borders colors will be reversed when the gadget is selected,
  113. but the background and text colors will be unaffected.    If you wish to make
  114. the entire button GadgHComp under IGRequest, you should select the
  115. GadgHComp option.  See the section on linking object events to functions,
  116. assigning keyboard commands, Changing an Objects font, and making a button
  117. end the requester for more information on these topics.
  118.  
  119.  
  120. Image Gadgets
  121. Requires 2.0 or above to Generate.
  122.  
  123. Can run under Intuition or GadTools
  124.  
  125. An Image Gadget is a boolean gadget or Button Kind with an image instead of
  126. text as a label.  The Image comes from any IFF brush.  The Image Gadgets
  127. tool is the third one down in the left column in the ToolBox.  You will
  128. have to assign the Image Gadget a structure name in the Struct Name field.
  129. You may specify the GadgetID in the GadgetID field.  You may turn off and
  130. on any of several options and Gadget Flags in the bank of Toggle gadgets in
  131. the lower left of the requester.  To specify the GadgetRender and
  132. SelectRender images click in the left and right blank boxes in the upper
  133. right area of the requester respectively.  A ASL file requester will appear
  134. allowing you to select an IFF brush.  You must specify a GadgetRender
  135. image, but a SelectRender image is optional; if none is specified, the
  136. gadget will be GadgHComp.  See also Button_Kind gadgets, linking object
  137. events to functions, assigning keyboard commands, and making a button end
  138. the requester for more information on these topics.
  139.  
  140.  
  141. String Gadgets
  142. Can be generated under 1.2 or above.
  143.  
  144. Can run under Intuition or GadTools
  145.  
  146. To generate String Gadgets, Integer gadgets, or String_Kind or Integer_Kind
  147. gadgets, use the String Gadget Tool, the second one down in the first
  148. column, or type "s."  You must specify a structure name for the gadget in
  149. the Struct Name field. The Label for this String Gadget is specified in the
  150. Label field.  You can also specify the width of the String Gadget in the
  151. Field Width field, its Gadget ID in the GadgetID field, the maximum
  152. allowable characters in the Max Chars. field, and the colors to be used for
  153. its labels and inner and outer borders in the Label Color, Border1 Color
  154. field, and Border2 Color field respectively.  The Label OffSet field
  155. specifies how far to the left of the String Gadgets field (editable area)
  156. the left edge of the Label appears. This will automatically be set for you
  157. when you specify the Label, but you may override it.  To create a Integer
  158. Gadget or an Integer_Kind Gadget, click the LongInt button in the bank of
  159. Toggle buttons at the left of the requester.  You can also turn on or off
  160. miscellaneous gadget flags here using their similarly named Toggle buttons.
  161. See controlling cursor movement between String Gadgets, specifying keyboard
  162. commands for objects, linking events to functions, and linking objects to
  163. structure fields for more information.
  164.  
  165.  
  166. Scroll Bars
  167. Can be generated under 1.2 or above.
  168.  
  169. Can run under Intuition or GadTools
  170.  
  171. To create a scroll bar, proportional gadget, or Scroller_Kind gadget use
  172. the Scroll bars tool, the fourth down in the first column.  The keyboard
  173. equivalent for this tool is "L."  A Scroll bar consists of a proportional
  174. gadget, an up arrow and a down arrow.  Under IGRequest all of these will be
  175. generated for you.  Under GTRequest, a Scroller_Kind Gadget which already
  176. includes all of these will be generated.  In the Scroll Bars Requester, you
  177. must specify the structure name to use in the Struct Name field.  The
  178. function to call when the scroll bar's position changes is in the Scroll
  179. Func field.  Under IGRequest its argument template is:
  180.  
  181.     void ScrollFunc (struct IGRequest *,struct Gadget *PropGadget,
  182.         LONG XPos,LONG YPos);
  183.  
  184. Under GTRequest its argument template is:
  185.  
  186.     void ScrollFunct(struct GTRequest *,struct IntuiMessage *,
  187.         struct GTControl *, struct MessageHandler *);
  188.  
  189. Under GTRequest, the IntuiMessage will be a duplicate of the MouseMove
  190. IntuiMessage received from GadTools, and its code field will contain the
  191. position for the XPos or YPos for the displayed area, depending on whether
  192. the Scroll bar is horizontal or vertical.
  193.  
  194. You can also specify the number of items that will be scrolled through and
  195. the number that can be displayed at once in the No. Items and No. Displayed
  196. fields if this information is known at this time.  By default, Scroll bars
  197. are vertical, however you can create a horizontal Scroll Bar by clicking on
  198. the Horizontal button in the upper right corner of the requester.  To
  199. specify the size of the Scroll Bar you can either type in the number of
  200. pixels high, or wide if you have selected horizontal, you wish the Scroll
  201. Bar to be in the Height/Width field, or you can use the Define button in
  202. the upper right corner.  For more information on using the define button
  203. see Defining sizes with the Define Button.  To specify GadgetID's for the
  204. Proportional gadget, the Up/Left Arrow Gadget, and the Down/Right Arrow
  205. Gadget, use the accordingly labeled fields.  Under IGRequest, all of these
  206. ID's are used.  Under GTRequest, only the GadgetID for the Proportional
  207. gadget is used.  Currently you cannot link keyboard commands to Scroll bars
  208. from within IntuiGen (although you can manually edit the code to do this).
  209.  
  210.  
  211. IntuiTexts
  212. Can be generated under 1.2 or above.
  213.  
  214. Can run under Intuition or GadTools
  215.  
  216. The IntuiTexts tools is the fifth one down in the first column in the
  217. ToolBox.  Its keyboard equivalent is "T."  In the IntuiText requester, you
  218. specify the structure name to be used in the Struct Name field, the text to
  219. be generated in the Text field, and the color registers to be used for the
  220. foreground and background colors in the FgPen and BgPen fields
  221. respectively.  If the Linked button is selected, the Text will be linked
  222. with all other texts whose link buttons were selected, and linked to any
  223. IG/GTRequest structure generated, causing them to be automatically drawn
  224. when the requester is opened.  If Linked is not selected, the IntuiText is
  225. not linked to anything, and will only be displayed if your code explicitly
  226. calls PrintIText on it.  For information on specifying the TextAttr's to be
  227. used, see Changing an Object's Font.
  228.  
  229.  
  230. Images
  231. Requires 2.0 or above to generate
  232.  
  233. Can run under Intuition or GadTools
  234.  
  235. To create an Intuition Image structure and Image data from an IFF Brush,
  236. use the Image tool, the sixth one down in the first column.  The Image
  237. requester requires only that you specify a structure name in the Struct
  238. Name field, and click in the empty box at the right to bring up a file
  239. requester in which you can specify the IFF brush to be used.  All Images
  240. are linked together and to the Requester of which they are a part and will
  241. automatically be displayed when that requester is opened.
  242.  
  243.  
  244. Boxes
  245. Can be generated under 1.2 or above.
  246.  
  247. Can run under Intuition or GadTools
  248.  
  249. A box is a pair of Border structures, one drawn in a light color, the other
  250. in a darker color, which create a highlighted box.  Optionally, the box may
  251. be in a single color. To create a box, use the box tool, the seventh one
  252. down in the first column in the ToolBox.  The keyboard equivalent for this
  253. tool is "x."  In the Box Requester you must specify the structure name in
  254. the Struct Name field, and the colors for the top and left, and bottom and
  255. right sides of the box in the Color1 and Color2 fields respectively.  To
  256. specify the size of the box, you may either enter a width and height in the
  257. Width and Height fields, or you may use the Define button.  See Defining
  258. sizes with the Define Button.  Note that if both Color1 and Color2 are the
  259. same, only one border structure will be generated as two are no longer
  260. necessary.
  261.  
  262.  
  263. Borders
  264. Can be generated under 1.2 or above.
  265.  
  266. Can run under Intuition or GadTools
  267.  
  268. Border structures can specify lines or polygons to be drawn in a requester.
  269. To create Border structures, use the Border tool, the eighth one down in
  270. the first column, or type its keyboard equivalent, "d."  This requester has
  271. only two field, the Struct Name field in which you must specify a structure
  272. name, and the Color1 field in which you specify the color of the line to
  273. draw.  You must then Define the Border by clicking on the Define Button.
  274. The procedure for doing this is slightly different than for Defining sizes
  275. for other Objects, so it will be documented here.  First click on the
  276. Define button.    The Object window is activated and brought to the front.
  277. Click in it at the beginning point for your border.  A line will begin to
  278. follow your pointer from this point to wherever you move it to.  Click the
  279. mouse button at each additional point you wish to establish.  On the last
  280. point, double-click.
  281.  
  282.  
  283. CheckBox_Kind
  284. Requires 2.0 or above to generate
  285.  
  286. Requires 2.0 or above to run
  287.  
  288. The Checkbox tool is the first tool down in the second column.    In the
  289. CheckBox_KInd requester, you must specify a structure name in the Struct
  290. Name field, and a label in the label field.  You can determine the Objects
  291. PlaceText attributes using the Cycle gadget in the middle left hand side of
  292. the requester.    You can turn on or off the Objects Disabled and Checked
  293. attributes using the Toggle buttons of the same name in the middle of the
  294. requester.  See also Changing an Object's Font, Assigning Keyboard Commands
  295. to Objects, Linking Events to Functions Under IG/GTRequest, and Linking
  296. Structure Fields to Objects for more information on these topics.
  297.  
  298.  
  299. MX_Kind
  300. Requires 2.0 or above to generate
  301.  
  302. Requires 2.0 or above to run
  303.  
  304. The Radio Button (MX_Kind) tool is the second tool down in the second
  305. column.  In the MX_Kind requester, you must specify a structure name in the
  306. Struct Name field, and a label in the Label field.  You can determine the
  307. Object's PlaceText attributes using the Cycle gadget in the middle left hand
  308. side of the requester.    To set up a list of Radio Button options for this
  309. Object, use the Editable list at the right of the requester.  To add a new
  310. entry, click on the New button, and enter the label in the text field
  311. beneath the Listview gadget.  To Change an entry, select it, then change
  312. its text in the text field beneath the Listview gadget, pressing return
  313. when done.  To delete an entry, select it, then click the Delete button.
  314. To determine which radio button is initially selected, enter its ordinal
  315. number in the Selected field.  See also Changing an Object's Font, Linking
  316. Events to Functions Under IG/GTRequest, and Linking Structure Fields to
  317. Objects for more information on these topics.
  318.  
  319.  
  320. Cycle_Kind
  321. Requires 2.0 or above to generate
  322.  
  323. Requires 2.0 or above to run
  324.  
  325. The Cycle_Kind tool is the third tool down in the second column.  In the
  326. Cycle_KInd requester, you must specify a structure name in the Struct Name
  327. field, and optionally specify a label in the Label field.  You can
  328. determine the Object's PlaceText attributes using the Cycle gadget in the
  329. middle left hand side of the requester.  To set up a list of cycle labels
  330. for this Object, use the Editable list at the right of the requester.  To
  331. add a new entry, click on the New button, and enter the label in the text
  332. field beneath the Listview gadget.  To Change an entry, select it, then
  333. change its text in the text field beneath the Listview gadget, pressing
  334. return when done.  To delete an entry, select it, then click the Delete
  335. button.  To determine which cycle options is initially selected, enter its
  336. ordinal number in the Selected field.  To disable the Cycle_Kind object,
  337. click the Disabled Toggle Button. Defaults for the Cycle_Kind's width and
  338. height will be set for you, however you may override them in the Width
  339. field and Height field. See also Changing an Object's Font, Linking Events
  340. to Functions Under IG/GTRequest, and Linking Structure Fields to Objects
  341. for more information on these topics.
  342.  
  343.  
  344. ListView_Kind
  345. Requires 2.0 or above to generate
  346.  
  347. Requires 2.0 or above to run
  348.  
  349. The ListView_Kind tool is the fourth tool down in the second column.  In
  350. the ListView_KInd requester, you must specify a structure name in the
  351. Struct Name field, and an optional label in the label field.  You can
  352. determine the Object's PlaceText attributes using the Cycle gadget in the
  353. middle left hand side of the requester.  You can make the Object read only
  354. by clicking the Read Only Toggle Button, or you can select the ShowSelected
  355. option you want in the cycle gadget below the PlaceText cycle gadget from
  356. one of the following:  No Display, View Only, or Editable.  To set the
  357. Object's width and height, change the numbers in the Width field and Height
  358. field, or use the Define button.  See also Defining Sizes with the Define
  359. Button, Changing an Object's Font, Linking Events to Functions Under
  360. IG/GTRequest, and Linking Structure Fields to Objects for more information
  361. on these topics.
  362.  
  363.  
  364. EditList Pseudokind
  365. Requires 2.0 or above to run
  366.  
  367. IntuiGen has no direct support for generating code for EditList pseudokinds
  368. (which are supported under GTRequest).  You should generate code for a
  369. ListView_Kind, and then change the first few lines of the corresponding
  370. GTControl structure to read as follows:
  371.         struct GTControl MyControl =
  372.         {
  373.                 &PreviousControlHere,
  374.                 "EditList",
  375.                 INITFROMDATA | STOREDATA | GTC_PSEUDOKIND,
  376.             ...
  377.         };
  378.  
  379.  
  380. Palette_Kind
  381. Requires 2.0 or above to generate
  382.  
  383. Requires 2.0 or above to run
  384.  
  385. The Palette_Kind tool is the fifth tool down in the second column.  In the
  386. Palette_KInd requester, you must specify a structure name in the Struct
  387. Name field, and an optional label in the label field.  You can determine
  388. the Object's PlaceText attributes using the Cycle gadget in the middle left
  389. hand side of the requester.  You can select the Indicator placement option
  390. you want in the cycle gadget below the PlaceText cycle gadget from one of
  391. the following:    Indicator (Ind.) Left, Ind. Above, or No Ind.  To set the
  392. Indicator's width or height, enter it in pixels in the Ind. W/H field.  To
  393. disable the Palette_Kind Object click on the Disable Toggle Button.  To set
  394. the Objects width and height, change the numbers in the Width field and
  395. Height field, or use the Define button.  See also Defining Sizes with the
  396. Define Button, Changing an Object's Font, Linking Events to Functions Under
  397. IG/GTRequest, and Linking Structure Fields to Objects for more information
  398. on these topics.
  399.  
  400.  
  401. Text_Kind
  402. Requires 2.0 or above to generate
  403.  
  404. Requires 2.0 or above to run
  405.  
  406. The Text_Kind tool is the sixth tool down in the second column.  In the
  407. Text_Kind requester, you must specify a structure name in the Struct Name
  408. field, and an optional label in the label field.  You can determine the
  409. Object's PlaceText attributes using the Cycle gadget in the middle left
  410. hand side of the requester.  To set the text to be displayed in the
  411. Text_Kind gadget, enter it in the Text field.  The Border Toggle Button
  412. determines whether this Object will have a border or not.  To set the
  413. Object's width and height, change the numbers in the Width and Height
  414. fields.  See also Changing an Object's Font for more information on this
  415. topics.
  416.  
  417.  
  418. Number_Kind
  419. Requires 2.0 or above to generate
  420.  
  421. Requires 2.0 or above to run
  422.  
  423. The Number_Kind tool is the seventh tool down in the second column.  In the
  424. Number_Kind requester, you must specify a structure name in the Struct Name
  425. field, and an optional label in the label field.  You can determine the
  426. Object's PlaceText attributes using the Cycle gadget in the middle left
  427. hand side of the requester.  To set the number to be displayed in the
  428. Number_Kind gadget, enter it in the Number field.  The Border Toggle Button
  429. determines whether this Object will have a border or not.  To set the
  430. Object's width and height, change the numbers in the Width and Height
  431. fields.  See also Changing an Object's Font for more information on this
  432. topics.
  433.  
  434.  
  435. Menus
  436. Can be generated under 1.2 or above.
  437.  
  438. Can run under Intuition or GadTools
  439.  
  440. To open the Menus requester, click on the Menus tool, the eighth down in
  441. the second column in the Tool Box, or press "m."  The Menu Window will
  442. open, and, after a short initialization delay, your cursor will appear in
  443. the upper left corner. This first String Gadget is the title of the
  444. left-most menu.  The Gadget to its right is the title of the second menu,
  445. and so on.  Beneath each menu title, are fifteen Gadgets representing that
  446. menu's items.  Only items for which there is text will be generated.  If
  447. there is a blank item between two filled items,  the TopEdge value of the
  448. second filled item will be adjusted accordingly, leaving it in its same
  449. position relative to the first.  Fill in the menus and menu items as you
  450. would have them generated.
  451.  
  452. To call up an information requester for any menu title or menu item, shift
  453. click on it. Note that the item upon which you are shift clicking cannot
  454. already be selected (the cursor can't be in that Gadget) when you do this,
  455. or no message will be sent to IntuiGen, and consequently, the requester
  456. will not appear.  If this happens, simply select another item, and then
  457. shift click on the desired one.
  458.  
  459. If you called up an information requester on a menu title, a Menu Info
  460. Requester with two String Gadgets and an "OK" Gadget will appear.  The
  461. "Struct Name:" Gadget contains the struct name of this menu.  If you
  462. entered the menu title before you added any of this menu's items, the
  463. struct name will be synonymous with the first title that you typed in,
  464. otherwise it will be "MenuX" where X is the number of the menu.  By
  465. automatically generating the structure name in this manner, you do not have
  466. to be bothered with assigning everything a struct name.  For future
  467. reference, the struct names as generated by IntuiGen will all be listed in
  468. the accompanying Summary (see summaries in the Generate Code Requester).
  469. The second Gadget, "Title:", reflects the title of this menu.  Click "OK"
  470. or hit return when you are finished.
  471.  
  472. If you called up an information requester on a menu item, a Menu Item Info
  473. Requester will appear with five String Gadgets, a bank of three
  474. Toggleselect Gadgets at the bottom, a box in which the subitems will go,
  475. and an "OK" and "Cancel" Gadget.  The "Struct Name:" field contains the
  476. structure name that will be used in generating the code.  This will
  477. automatically contain the structure name of the menu of which this item is
  478. a part as taken at the time of the item's creation, followed by the word
  479. "Item" and then the item's number, where the first item in a menu is zero
  480. and the last is fourteen.  The "Text:" field contains the text for that
  481. item, and the "Select Text:" field contains the SelectText for that item.
  482. The "Command:" field contains the single letter command that will activate
  483. that item when pressed in conjunction with the right Amiga key.  The
  484. "Function:" field contains the name of the function that is to be called
  485. when this menu item is chosen under GTRequest or IGRequest.  This function will be
  486. passed the address of the IG/GTRequest structure and the address of a copy of
  487. the IntuiMessage structure.  The "ITEMENABLED," "CHECKIT," and "CHECKED"
  488. Gadgets turn on and off their corresponding flags in the MenuItem
  489. structure.  To add subitems, click in the box in the upper middle of the
  490. requester, and enter the subitem's text.  You may bring up an information
  491. requester on a subitem in the same manner in which you brought up the Menu
  492. Item Info Requester.  The SubItem Info Requester operates exactly like the
  493. Menu Item Info Requester, except that it has no provisions for subitems.
  494.  
  495. When you are finished with the Menus Requester, click the close Gadget in
  496. the upper left corner of the Window.  If you wish to change these entries
  497. later in a session, click on the Menus tool again, or press "m."  The Menus
  498. Requester will appear with your entries, allowing further editing.
  499.  
  500.  
  501. Preferences
  502. Can be set under 1.2 and above
  503.  
  504. Code generation Not Applicable
  505.  
  506. To open the Preferences Requester, click on the Preferences Gadget in the
  507. Tool Box, the or press "p."  The preferences requester allows you to set
  508. the IntuiGen colors to match those of the program you are developing, and
  509. set the IntuiGen screen to interlaced or non-interlaced.  Setting the
  510. IntuiGen colors to match those of your program allows you to see how your
  511. layout will look in your program, and helps you in setting Border colors
  512. for various Gadgets and such.  Also, IntuiGen will generate a Color Table,
  513. with which you can set your program's screen's colors, using its current
  514. colors when you are ready to generate code. You are, of course, limited to
  515. four colors, as IntuiGen sets itself up on a four color Screen.  You can
  516. work around this though by limiting your User-Interface items to the first
  517. four colors of your screen, reserving the rest for other items.
  518.  
  519. To set a given color register, click on its representative color square, so
  520. that it is surrounded by a pink (or whatever color register three happens
  521. to be defined as) box.    Below the color select squares are three
  522. Proportional Gadgets.  Each of these is labeled with one of the primary
  523. colors, and next to the label is written that color's numerical value.  By
  524. adjusting the proportional Gadget, either directly or with the arrows, you
  525. can change that primary color's value in the chosen color register. When
  526. the color registers tone suits you, you can repeat the process with the
  527. remaining registers.
  528.  
  529. The "Laced" Gadget in the lower left corner sets the Screen to interlaced
  530. or non-interlaced.  If no Objects (includes everything but menus, and
  531. IGRequest information) have been created, leaving the Object Window and
  532. Clips Window empty, the Screen will be changed when you press "Use," or
  533. "Save."  Otherwise, this Gadget can only be used in setting the saved
  534. preferences.
  535.  
  536. When all the registers have been properly adjusted, you can end the
  537. requester in one of three ways.  You can click on "Use," which will use the
  538. selected colors for the current session, "Save," which will save the
  539. selected colors for use in future sessions, or "Cancel," which will return
  540. the color registers to their state prior to your calling up the Preferences
  541. Requester.
  542.  
  543. Preferences are also automatically saved as part of the IntuiGen file.
  544. Clicking "Save" in the Preferences Requester saves global preferences which
  545. will be used each time you load IntuiGen without also opening a project
  546. file.  When you load a project file, however, the current preferences will
  547. be overridden by those in the file.
  548.  
  549. All global preferences data is saved as a ToolType in the IntuiGen.info
  550. file.  If this file is missing, global preferences cannot be saved.  They
  551. still can, however, be saved on a file by file basis.  See Saving and
  552. Loading.
  553.  
  554.  
  555. Color Tables
  556. Can be generated under 1.2 or above.
  557.  
  558. Can run under Intuition or GadTools
  559.  
  560. To instruct IntuiGen to include a Color Table with your code listing,
  561. select the "Color Table" Gadget in the Generate Code Requester.  Your Color
  562. Table will automatically be given the structure name of "ColorMap." (That's
  563. excluding the period).    To set the colors of a given Screen "Screen" to
  564. those specified by the Color Table, use the following command (Note that
  565. the Graphics Library must be open):
  566.  
  567. LoadRGB4 (&(Screen->ViewPort),ColorMap,4);
  568.  
  569.  
  570. The following is a sample Color Table:
  571.  
  572. USHORT ColorMap[] =
  573. {
  574.     3822,
  575.     273,
  576.     3549,
  577.     3980,
  578. };
  579.  
  580.  
  581. Changing Objects
  582. To change any Object in the Object Window, double click on it. This will
  583. bring up the original requester used to create the Object, with the
  584. original information.  Make any changes you would like, and click "OK."  If
  585. you change your mind and decide to abandon your changes, click "Cancel."
  586.  
  587.  
  588. Positioning Objects
  589. To move an Object, click on it with the select button.          It will be
  590. highlighted.  Position the mouse where you would like the upper left corner
  591. of the Object to be, and click the select button again.  The Object will be
  592. moved to the chosen location.  You can also move an Object one pixel at a
  593. time, using the arrow keys.  Please note that String Gadgets are positioned
  594. by the upper left corner of their text entry box, not by the upper left
  595. corner of their label.    At the bottom of the Tool Box will be two sets of
  596. coordinates. The bottom one, in color one (defaults to black), are the
  597. current coordinates of the mouse pointer relative to the active Window
  598. (which should, at this point, be the Object Window).  The second one, in
  599. color three (defaults to pink), are the coordinates of the selected Object.
  600.  
  601. To move a group of Objects, click on the first Object in the group, and the
  602. shift-click on the rest of the Objects.  They will all be highlighted.    The
  603. Object coordinates (color three, pink) will reflect the topmost, left-most
  604. Object, which is the handle.  Move the pointer to where you would like the
  605. handle positioned, and click the select button.  The handle will be
  606. positioned under your pointer, and all the other selected Objects will be
  607. moved to retain their same positions relative to the handle.  To de-select
  608. the group, click on any Object, and then it alone will be selected.  After
  609. a short pause (don't double click on it), click on it again, and it will be
  610. de-selected, leaving your Window as it will look when created from the
  611. generated code.  Again, you can move the group a single pixel at a time
  612. using the arrow keys.
  613.  
  614. One of the most useful features of IntuiGen is Automatic Positioning.  This
  615. can be made to work in several ways.  The first way is to select "Object
  616. Position" from the "Windows" menu, or press "Enter" (on the numeric keypad)
  617. when no Object or group is selected.  This brings up a small requester that
  618. allows you to choose whether newly created Objects will be placed in the
  619. Object Window in Rows (across the screen) or in Columns (up and down).  Two
  620. String Gadgets allow you to set the Horizontal Offset or the Vertical
  621. Offset between the Objects.  This reflects the number of pixels in between
  622. each Object.  If you invoke this requester, either through the menu or from
  623. the keyboard, when a single Object is selected, it allows you to set the
  624. coordinates of the LeftEdge and TopEdge numerically.  This can be useful
  625. when trying to move an Object to specific coordinates.    If you invoke this
  626. requester when a group of Objects is selected, you have the option to move
  627. the group to a specific set of coordinates as above, but you can also
  628. re-arrange the group so that it is in a row or column.    To do this, simply
  629. select the Gadget representing the desired arrangement (row or column), and
  630. set the offset.  When you click "OK" the group of Objects will be
  631. re-arranged, with the topmost left-most Object in either the top or left
  632. position (depending upon whether you selected "Row" or "Column"), the
  633. second topmost left-most Object in the second position, and so on.
  634.  
  635. A few other things should be noted.  The first of these is unique handling
  636. when Boxes and Borders are involved.  A Box or Border can be quite large,
  637. and will often have other Objects inside of it.  But clicking inside of it
  638. to position an Object or a group of Objects would de-select the Object or
  639. group, and select the Box or Border.  For this reason, when an Object or
  640. group is selected, clicking on a Box or Border is treated like clicking on
  641. an unoccupied space in the Window, that is, the selected Object or group is
  642. moved, and the Box or Border is not selected.  To select a Box or Border,
  643. you must first de-select everything, and then click on them.  Then they can
  644. be moved or included in a group like anything else.
  645.  
  646. Another feature is the ability to change the way the Objects are layered.
  647. When two Objects are on top of one another, and the mouse is clicked over
  648. both of them, the topmost one will be selected.  To change which one is the
  649. topmost one use the "8" and "2" keys on the numeric keypad.  You can
  650. remember these keys, because on their side, the have an up arrow and a down
  651. arrow painted on them respectively.  They work as Bring to Front, and Send
  652. to Back for the selected Object.  When using them, remember, Boxes and
  653. Borders are automatically kept behind everything else.    Sending a Boolean
  654. Gadget to the back would send it behind everything but Boxes and Borders.
  655. Likewise, bringing a Box to the front would bring it in front of all other
  656. Boxes and Borders, but it would still be behind all other Objects.
  657.  
  658. You can move Objects or groups into the Clips Window in the same way that
  659. you would move them within the Object Window.  You can later move them back
  660. using the same procedure.  No code is generated for Objects left in the
  661. Clips Window, but they are saved when you use the save command, and will be
  662. restored when you later re-load the saved file (see Saving and Loading).
  663.  
  664.  
  665. Deleting Objects
  666. When you press the Delete key, the selected Object or group will first be
  667. removed to the Clips Window.  If they are already in the Clips Window when
  668. you press Delete, they will be truly deleted.  Hence, pressing delete twice
  669. will completely eradicate the current Object or group.
  670.  
  671.  
  672. Auto Struct Names
  673. In certain circumstance, where you are creating a large series of Objects,
  674. it would be advantageous to have numbered struct names that would be
  675. automatically carried through for each new Object of that type.  To do
  676. this, when you create your first Object just type something similar to
  677. "StructNameHere1" or "MyGadget23" for the struct name.  The next time you
  678. call that requester, the "Struct Name:" field will already be filled in
  679. with "StructNameHere2" and "MyGadget24" respectively.  Also, the GadgetID's
  680. for the different Gadget tools will automatically increment by one.
  681.  
  682.  
  683. IntuiGen Key Commands
  684. Pressing the Help key will open a Window containing a list of all the
  685. keyboard commands, including Load, Save, Send to Front, Send to Back, and
  686. Delete.
  687.  
  688.  
  689. Object Fonts
  690. The label font of any Object whose requester has a Font/Style button may be
  691. changed.  Clicking on this button will bring up a Text Attributes Requester
  692. listing various text attributes.  Use the mouse to turn off and on the
  693. desired features and then click "OK."
  694.  
  695.  
  696. Defining Sizes
  697. The "Define" Gadget is an easy way to set the height or width of an Object.
  698. When you click on it the open requester will temporarily be cleared and the
  699. message "Define Height/Width" will be displayed.  To define the height and
  700. width, place the pointer where you would like the upper left corner of the
  701. Object to appear in the Object Window, then press and hold the left button.
  702. Notice that the current mouse coordinates are displayed in the bottom part
  703. of the Tool Box.  While continuing to hold the mouse button, move the
  704. pointer to where you would like the lower right corner of the Object to be.
  705. As you move the mouse, a box should be drawn and updated reflecting the
  706. size and position of the Object.  When the box is adequately sized, let go
  707. of the mouse button.  The open requester will reappear, and the appropriate
  708. height or width will be entered into the Height and Width fields.
  709.  
  710.  
  711. Saving/Loading IGen
  712. The Saving and Loading Requesters can be invoked by selecting "Save Igen"
  713. and "Load Igen" from the "Project" menu or hitting control-S and control-L,
  714. respectively. Under Release 2 and above, an ASL file requester will appear.
  715. On pre-2.0 machines, a requester with a single String Gadget into which you
  716. can enter the path and file name of the file you are trying to load or save
  717. will appear.  It is recommended that you append the file extension ".IGen"
  718. on to all IntuiGen files to make them easy to identify. Also note that when
  719. saving, any file existing under the given path and file name will be
  720. renamed with the extension .BAK.  Any existing .BAK file will be deleted.
  721.  
  722. All Objects, Menus, Preferences settings, and Window sizes and positions
  723. are saved to the file and restored when it is loaded.  If you have created
  724. or loaded Objects in IntuiGen, and then load another .IGen file, the Menus,
  725. Preferences, and Window settings of the loaded file will override and
  726. replace the current parameters.  However, Objects in memory will not be
  727. affected; the Objects in the loaded file will simply be added to the
  728. current Object list.  This provides a mechanism for combining files or
  729. inserting one file into another.
  730.  
  731.  
  732. End Buttons
  733. You can cause a Button Object or an Image Button Object to end the
  734. requester when they are clicked on.  In the lower middle-right of each
  735. requester are a set of Toggleselect Gadgets labeled IGEndGadget, and
  736. FillStruct.  If you want your GTRequest or and IGRequest to end when this
  737. Gadget is selected, or its keyboard command is typed, select IGEndGadget.
  738. If this Gadget is an IGEndGadget, if your data structure is to be filled
  739. (an OK-type Gadget) when this Gadget is chosen, choose FillStruct.  If the
  740. data structure should be left as is (a Cancel-type Gadget), do not select
  741. FillStruct.  Above these two Toggleselect Gadgets is a String Gadget
  742. labeled End Func.  If this is an IGEndGadget, and a function name is given
  743. in this field, this function will be called before IGRequest terminates.
  744. Note that the object's GadgetUp and GadgetDown functions, if applicable,
  745. will be called first.
  746.  
  747.  
  748. Limiting String Gadgets
  749. You can enter any  characters that should not be allowed in a String Gadget
  750. in the Invalid Chars field in the String Gadgets requester.  If a user
  751. types any character found in this field under IGRequest or GTRequest, they
  752. will be automatically removed by GT/IGRequest on the next message from that
  753. requester (GadgetDown, GadgetUp, MouseButtons, etcetera).
  754.  
  755. Many times String Gadgets will be used for numerical quantities rather than
  756. text. IGRequest supports floating point String Gadgets (can be defined as
  757. float or double in IGRequest.c or GTRequest.c, in the Source directory on
  758. the IntuiGen disk), SHORT String Gadgets, and LONG String Gadgets.  These
  759. are chosen by selecting the "Float," "Long," and "Short" Toggleselect
  760. Gadgets, respectively.    If one of these types is chosen, the Struct Field
  761. is assumed to be of the same type, not a string, and whatever value is
  762. entered into the String Gadget will be converted to a number of the
  763. appropriate type before it is entered into your structure field.  (See
  764. linking Objects to Structure fields).  For types of SHORT and LONG, select
  765. the "LONGINT" Gadget to limit the characters that can be typed into the
  766. Gadget.  Do not select "LONGINT" for floating point Gadgets, as this will
  767. prevent the user from entering a decimal point. Regardless of type (Long,
  768. Short, Float), or whether or not "LONGINT" is selected, IG/GTRequest will
  769. automatically assume that all characters save the digits 0-9, the minus
  770. sign, and the period, are "Invalid" and will treat them in a identically to
  771. Invalid Characters.  You need not enter anything into the "Invalid Chars:"
  772. field.    To set limits on these on numerical String Gadgets, fill in the
  773. "High:" and "Low:" fields.  If these are left blank, it is assumed there
  774. are no limits.    Otherwise the numbers entered will automatically be forced
  775. to be between or equal to these numbers.  Note that it is legal to enter
  776. just one limit, i.e. enter 0 in the Low field and leave the high field
  777. blank.    In this case there would be no high limit.
  778.  
  779.  
  780. String Gadget Cursor GadgetUp Movement
  781. One of the most convenient features for a user entering data into a
  782. requester is hitting Return and having the next String Gadget automatically
  783. activated.  The "Next String:" field in the String Gadget requester
  784. contains the structure name of the String Gadget to be activated when a
  785. GadgetUp message is received from the requester.  If the Toggleselect
  786. Gadget "Next," located to the right of the "Next String:" Gadget, is
  787. selected when you create a String Gadget (which it is by default), then the
  788. next String Gadget you create will automatically be entered into this
  789. field.    In the event that this is the last String Gadget you create, having
  790. "Next" selected will have no effect.
  791.  
  792.  
  793. Window Size Position
  794. The Window Size/Position Requester is brought up by clicking on the Object
  795. Window resizing Gadget, resizing the Object Window, or choosing "Window
  796. Size/Position" from the "Windows" Menu.  It consists of four String
  797. Gadgets, "To Window" and "From Window" boolean Gadgets, and "OK" and
  798. "Cancel" Gadgets.
  799.  
  800. In the four String Gadgets you will find the Object Window's LeftEdge,
  801. TopEdge, Width, and Height values.  You may change these to anything you
  802. like.  Clicking on the "To Window" Gadget will resize and reposition the
  803. Object Window to match the numbers in these four String Gadgets.  You can
  804. also resize and reposition the Object Window itself, and then click the
  805. "From Window" Gadget, which will update the String Gadgets to match the new
  806. Window coordinates.
  807.  
  808. When you are satisfied with the Object Window's position, you can close the
  809. requester in one of three ways.  The first way is to click on the close
  810. Gadget on the Window Size/Position Window.  When you do this, the Object
  811. Window will retain whatever size and position it currently has, regardless
  812. of coordinates the LeftEdge, TopEdge, Width, and Height Gadgets contain.
  813. The second way is to click "OK" in the Window Size/Position requester.  The
  814. Object Window will be resized and repositioned to match the String Gadget
  815. coordinates.  The third way is to hit return.  This will have the same
  816. effect as choosing "OK."
  817.  
  818. To cancel the changes that you have made to the Object Window's size and
  819. position, click "Cancel" or hit escape.  The Object Window will return to
  820. its previous size and position.
  821.  
  822.  
  823. Card File Tutorial
  824. Type IntuiGen on the command line and press return.  We will be using
  825. IntuiGen and GTRequest to create a simple card file to hold names and
  826. addresses.  If you would prefer to read a saved version of the tutorial
  827. from disk, the IGen file (that can be loaded into IntuiGen via the Load
  828. command), complete source file, and executable file are all in the Examples
  829. directory on the IntuiGen disk.  First we will look at the data structure
  830. that we will be using:
  831.  
  832. struct Person {
  833.     struct Person    *Next,*Prev;
  834.     UBYTE    Name[100],
  835.             Address[100],
  836.             CityStateZip[100];
  837.     SHORT    Age;
  838. };
  839.  
  840. We will have our Window simulate one card, with Gadgets to change the card
  841. we are looking at.  We will also have a Gadget for adding new cards.  We
  842. will have one menu, called Project, with items "Load," "Save," and "Quit."
  843. The user will also be able to type control-c to quit.  Global variables
  844. will be the pointer to the currently displayed card, OnScreen, the base of
  845. the list, CardBase, a Remember key upon which new cards will be allocated,
  846. CardKey, and a flag to be set when the program is to terminate, QuitFlag.
  847. Functions we will have to write will be main, NewCard, Quit, LoadStuff, and
  848. SaveStuff, although for the purposes of this tutorial, we will not be
  849. expanding LoadStuff and SaveStuff; they will simply print their names to
  850. the console indicating that they were called.
  851.  
  852. The first set of Gadgets that we will generate will be the String Gadgets
  853. "Name:," "Address:," "City, State, Zip:," and "Age:."  They will be
  854. arranged into a column.  To facilitate this, select "Object Position" from
  855. the "Windows" menu.  Select Column, and leave the vertical offset at zero.
  856. (See Positioning Objects). Then press "OK."  Next hit "s" on the keyboard
  857. to bring up the String Gadgets Requester.  For the Struct Name, enter
  858. "NameGad".  For the label enter "Name:".  For Gadget Activation Flags
  859. select "RELVERIFY," and "GADGIMMEDIATE."  Activate the "Struct Field:"
  860. field and enter "Name".  For maximum characters enter 100.  Then click
  861. "OK."  Notice that we are leaving the "Next" Gadget selected so that the
  862. next Gadget we create will automatically be entered as the Gadget to
  863. activate on a GadgetUp message from this one.  (See Cursor movement between
  864. String Gadgets).  Move the "Name:" Gadget to
  865. the center of the Window.
  866.  
  867. Press "s" again.  This time enter "AddressGad" for the struct name,
  868. "Address:" for the label, and "Address" for the Struct Field.  The Gadget
  869. Activation and maximum characters will remain the same from the previous
  870. Gadget.  Click "OK."  Your second String Gadget will appear immediately
  871. below the first, in a perfect column.  Create the "City, State, Zip:"
  872. Gadgets using an identical procedure.
  873.  
  874. Press "s" one last time.  Enter "AgeGad" for the struct name, "Age:" for
  875. the label, and "Age" for the struct field.  Select "LONGINT" as a Gadget
  876. Type, and Short down below, as the struct field type.  Click "OK."
  877.  
  878. Next we will create a series of Boolean Gadgets that are to be arranged in
  879. a row. With no Objects selected, hit enter on the numeric keypad to bring
  880. up the Auto Positioning Requester.  Select "Row."  Leave the XOffSet zero.
  881. Click "OK."  Press "b" to call up the Button Gadgets Requester.  For a
  882. struct name, enter "PreviousGad". For the Gadget Text, enter "Previous".
  883. Next click on the keyboard command String Gadget.  Enter "p".  Select
  884. "IGEndGadget" and "FillStruct."  We will have the requester end, change
  885. OnScreen to point to the new card, and call GTRequest again.  To prevent
  886. the Window from re-opening and closing, we will open in our main routine,
  887. and set the NewWindow pointer in the GTRequest structure to NULL.
  888.  
  889. Create another Button Gadget.  Set its struct name to NextGad, its text to
  890. "Next", and its keyboard command to "n".  Leave "IGEndGadget" and
  891. "FillStruct" selected. Create a third labeled "New".  Make sure it has a
  892. unique keyboard command, don't use "n" again.  Click on the "Previous"
  893. Gadget and shift-click on the "Next" and "New" Gadgets.  Move your pointer
  894. down below the String Gadgets and click.
  895.  
  896. Press "t" to invoke the IntuiTexts requester.  For the struct name type
  897. "Title".  For the text, type "IntuiGen Generated Card File".  Select
  898. "Linked."  Click on "Font/Style."  In the Text Attributes Requester, select
  899. bold, underlined, italic, extended, and Topaz_Sixty.  (See Object Fonts).
  900. Click "OK." in both requesters.  Your IntuiText will likely appear next to
  901. your "New" Gadget, possibly with some outside of the Window, and thus not
  902. visible. Click on the visible portion of it and move it up above the String
  903. Gadgets.
  904.  
  905. Next, press "x" to bring up the Boxes Requester.  For the struct name type
  906. "Box". Then click define.  Draw a box around all of the other Objects in
  907. the Window.  Then click "OK" in the Boxes Requester.
  908.  
  909. Click on the box, and then shift-click on all the other Objects.  Move them
  910. to the top left corner of the Window.  Then click on any Object besides the
  911. box to de-select the group.  Resize the Window so it just fits your
  912. requester.  Click "OK" in the Window Size Position Requester that will then
  913. appear.
  914.  
  915. Click "m" to bring up the Menus Requester.  Type "Project" into the first
  916. Menu field. Press return to move to the first MenuItem field.  Type "Load".
  917. Press return and type "Save", and then for the third MenuItem enter "Quit".
  918. Shift-click on the "Load" item. Enter "LoadStuff" into the "Function:"
  919. field.    Click "OK" in the Menu Item Info Requester.  Bring up the info
  920. requester on the "Save" item.  For its function enter "SaveStuff".  For the
  921. Quit item's function, enter "Quit".  Then close the Menu Window.
  922.  
  923. Click "r" to bring up the IG/GTRequest Info Requester.  For struct name, enter
  924. "CardRequest".  For struct type, enter "Person".  Enter "c" into the Ending
  925. keyboard command String Gadget, select "Ctrl" as the Qualifying key, and
  926. select "FillStruct" to have GTRequest fill our structure for us.  Then
  927. click "OK."
  928.  
  929. Click "Write Code" in the Tool Box.  (See Generating Code).  Type in
  930. convenient code and summary names. Select "Window Listing," "IG/GTRequest
  931. Code," "GadTools Code," and "Summary."  Click "OK."  For the Window struct
  932. name type "CardFileWindow".  For the title, enter "IG Card File".  Click
  933. "OK."  Click "OK" in the Window Size/Position Requester for both the
  934. minimum and maximum sizes.  Select GadgetDown, GadgetUp, MenuPick, and
  935. RawKey for IDCMP flags. Select DragBar, DepthGadget, Smart_Refresh, and
  936. Activate for Window Flags. In the Save Igen Data Requester enter a
  937. convenient file name, and press return to save your Igen data file.  The
  938. program will then terminate.
  939.  
  940. Load the generated code file into your text editor.  Notice that IntuiGen
  941. generated over 700 lines of structure definitions just for this project.
  942. At the top of the file, include stddef.h, stdlib.h, Exec/Exec.h,
  943. Intuition/Intuition.h, IntuiGen/IntuiGen.h, and IntuiGen/GTRequest.h.
  944. Define IntuitionBase, GadToolsBase, and GfxBase.  Declare struct Person,
  945. CardBase, OnScreen, and CardKey and QuitFlag, which should both be
  946. initialized to zero.  Declare the functions (as returning void) LoadStuff,
  947. SaveStuff, and Quit.  Move to the bottom of the file.  Change the NewWindow
  948. field in the CardRequest structure to NULL.  Type a LoadStuff function that
  949. takes as arguments a pointer to a GTRequest structure, and a pointer to an
  950. IntuiMessage structure.  Have it print "LoadStuff" to the console.  Type a
  951. SaveStuff function that has identical arguments to the LoadStuff function.
  952. Have it write "SaveStuff" to the console.  Write a Quit function, taking
  953. the same arguments, that calls GTEndRequest with a termination value of 1.
  954. Then type in the following functions:
  955.  
  956. BOOL NewCard ()
  957. {
  958.     struct Person *new;
  959.  
  960.     new=AllocRemember (&CardKey,sizeof (struct Person),MEMF_PUBLIC |
  961. MEMF_CLEAR);
  962.     if (!new) return (1);
  963.     if (OnScreen->Next) OnScreen->Next->Prev=new;
  964.     new->Next=OnScreen->Next;
  965.     new->Prev=OnScreen;
  966.     OnScreen->Next=new;
  967.     OnScreen=new;
  968.     return (0);
  969. }
  970.  
  971. main ()
  972. {
  973.     IntuitionBase=OpenLibrary ("intuition.library",0);
  974.     GfxBase=OpenLibrary ("graphics.library",0);
  975.     GadToolsBase=OpenLibrary ("gadtools.library",0);
  976.  
  977.     if (!IntuitionBase || !GfxBase || !GadToolsBase) goto done;
  978.  
  979.     CardRequest.Window=OpenWindowTagList (NULL,NewCardFileWindowTags);
  980.     if (!(CardRequest.Window)) goto done;
  981.  
  982.     OnScreen=&CardBase;
  983.     NewCard ();
  984.     while (!QuitFlag) {
  985.     CardRequest.DataStruct=(APTR)OnScreen;
  986.     if (!GTRequest (&CardRequest)) break;
  987.     if (GetEndControl(&CardRequest)==&NewGad) NewCard ();
  988.     else if (GetEndControl(&CardRequest)==&NextGad && OnScreen->Next)
  989.         OnScreen=OnScreen->Next;
  990.     else if (GetEndControl(&CardRequest)==&PreviousGad &&
  991. OnScreen->Prev!=&CardBase)
  992.         OnScreen=OnScreen->Prev;
  993.     }
  994.  
  995. done:  if (IntuitionBase) {
  996.        FreeRemember (&CardRequest.ReqKey,1);
  997.        FreeRemember (&CardKey,1);
  998.        if (CardRequest.Window) CloseWindow (CardRequest.Window);
  999.        CloseLibrary (IntuitionBase);
  1000.     }
  1001.     CloseLibrary(GadToolBase);
  1002.     if (GfxBase) CloseLibrary (GfxBase);
  1003. }
  1004.  
  1005. Save and compile this program, and then link it with GTRequest.c, found in
  1006. the Source directory on your IntuiGen disk.
  1007.  
  1008.  
  1009. Generating Code
  1010. To bring up the Generate Code Requester, click on the "Write Code" Gadget
  1011. in the ToolBox (the bottom Gadget on the right side), select "Generate
  1012. Code" from the "Project" menu, or press "c," or "q."  Under Release 2 or
  1013. higher, two ASL file requesters will appear, in sequence, immediately after
  1014. you click the Write Code gadget.  The first one allows you to enter the
  1015. filename to save the generated C Source code under.  The second allows you
  1016. to enter the filename, if any, to save a summary under.  Summaries are
  1017. explained in detail below.  Once you have responded or Canceled both of
  1018. these requesters, the Generate Code requester will appear.  If you are
  1019. working on a pre-Release 2 machine, the Generate Code requester will appear
  1020. immediately.  In the Generate Code Requester, we find two String Gadgets,
  1021. several Toggleselect Gadgets, an "OK" Gadget, "Cancel" Gadget, and a "Quit"
  1022. Gadget.  The "Write Code To:" String Gadget should contain the pathname and
  1023. filename to which you would like the C source code for your Objects and
  1024. Requester written.  If you used the ASL file requester to select a
  1025. path/filename to write code to, that path/filename will appear here.  Note
  1026. that any previous file existing in the given directory under the given
  1027. filename will be renamed with the extension .BAK.  Any existing .BAK file
  1028. will be deleted.  The "Write Summary To:" String Gadget should contain the
  1029. pathname and filename to which you would like the summary for set of
  1030. Objects written.  The summary will only be written if the "Summary" Gadget
  1031. at the bottom of the requester is selected. Again, note that any previous
  1032. file existing in the given directory under the given filename will be
  1033. renamed with a .BAK extension and any .BAK file will be deleted.
  1034.  
  1035. A summary consists of a list of the Objects written, their types, structure
  1036. names, coordinates, and GadgetIDs.  This can be extremely useful when
  1037. integrating the IntuiGen generated code into your program, or when making
  1038. changes at a later date. To have a Summary written, specify a Summary
  1039. filename, and click the Summary Toggle Button in the Generate Code
  1040. Requester.
  1041.  
  1042. For a Window Listing, Screen Listing, or Color Table Listing, select the
  1043. appropriate Gadgets at the bottom of the requester before choosing "OK."
  1044. These options will be discussed in their own sections shortly.    To have
  1045. IGInfo code and an IGReques structure generated, select "IG/GTRequest
  1046. Code."
  1047.  
  1048. To have GadTools Code written, select GadTools Code.  If GadTools Code and
  1049. IG/GTRequest Code are selected, GTRequest code will be written instead of
  1050. IGRequest code, and the system structures written will be for the GadTools
  1051. library, and not Intuition.
  1052.  
  1053. To write the source code, and summary, and end the current IntuiGen
  1054. session, click "OK."  To return to the program, click "Cancel."  To exit
  1055. IntuiGen without writing any code or summary, click "Quit."  After you have
  1056. generated code, or if you have chosen "Quit," the Save IGen Data Requester
  1057. will appear, allowing you to save your work as a proprietary file that can
  1058. later be retrieved into IntuiGen.  No String Gadgets in this requester will
  1059. be activated, however, providing an easy means to either save the file
  1060. under any previous filename by pressing return, or exit by pressing escape.
  1061. For more information see Saving and Loading.
  1062.  
  1063.  
  1064. Window Listings
  1065. To Generate a Window Listing, select the "Window Listing" Gadget in the
  1066. Generate Code Requester before selecting "OK."  This will cause the Get
  1067. Window Info Requester to be invoked when you select "OK" in the Generate
  1068. Code Requester.  In this Requester are two text fields, the "Struct Name:"
  1069. field, and the "Title:" field.  The "Struct Name:" field contains the
  1070. structure name that is to be used to generate the Window structure.  The
  1071. "Title:" field contains the title of the Window to be generated. Once these
  1072. are filled in, click "OK," or if you no longer wish to create a Window
  1073. structure, click "Cancel."
  1074.  
  1075. After you have clicked "OK" in the Get Window Info Requester, a message
  1076. will appear telling you to size the Object Window to the minimum dimensions
  1077. which you wish it to have.  The Window Size/Position Requester will appear
  1078. to help facilitate this (see Window Size/Position Requester).  After you
  1079. have set the minimum limits, the message will change, now instructing you
  1080. to size the Object Window to its maximum allowable dimensions.    Again the
  1081. Window Size/Position Requester will appear to help facilitate this.
  1082.  
  1083. After the maximum and minimum limits have been set, the IDCMP Flags
  1084. Requester will appear.    Select the appropriate IDCMP flags for your Window,
  1085. then click "OK." Next the Window Flags Requester will appear.  Select the
  1086. appropriate Window Flags and click "OK."  The Get Window Info Requester
  1087. will then terminate, and your code will be written to the chosen file. Note
  1088. that if GadTools Code is selected in the Generate Code requester, a taglist
  1089. will be written for OpenWindowTagList.    Otherwise, a NewWindow structure
  1090. will be written.
  1091.  
  1092.  
  1093. Screen Listings
  1094. To open the Get Screen Info Requester, select the "Screen Listing" Gadget
  1095. in the Generate Code Requester before clicking "OK."  The "Struct Name:"
  1096. field represents the structure name that will be used in writing the code
  1097. for the Screen.  The "Title:" field represents the title for this Screen.
  1098. The "Depth:" field contains the number of bitplanes to be allocated for
  1099. this Screen.  After you have filled in these fields, click "OK," or
  1100. "Cancel."
  1101.  
  1102. After clicking on "OK," the View Modes Requester will appear.  Select the
  1103. appropriate View Modes, then click "OK."  Your Screen will now be written
  1104. into the code file.  Note that if GadTools Code is selected in the Generate
  1105. Code requester, a taglist will be written for OpenScreenTagList. Otherwise,
  1106. a NewScreen structure will be written.
  1107.  
  1108.  
  1109. Object Key Commands
  1110. You can assign keyboard commands to Button Objects, Image Button Objects,
  1111. String Gadget Objects, and CheckBox_Kind Objects in IntuiGen.  If you
  1112. generate IGRequest or GTRequest code, (see Generating Code) these commands
  1113. will automatically be implemented.  If you do not generate IG/GTRequest
  1114. code, it is up to you to implement these commands, and entering them into
  1115. IntuiGen is superfluous.
  1116.  
  1117. To assign a keyboard command to an Object, find in its requester a bank of
  1118. Toggleselect Gadgets labeled "Ctrl," "Alt," "Amiga," and "Shift."  Next to
  1119. these is a small String Gadget.  The String Gadget contains the main letter
  1120. on the key cap for the keyboard command for this Gadget under IGRequest.
  1121. Special characters, such as Control-A, should not be typed into this
  1122. Gadget.  To have special characters recognized by your program under
  1123. IGRequest, select the accompanying Toggleselect Gadget.  For instance, if
  1124. you wanted the keyboard command for this Gadget to be Control-A, you would
  1125. type "a" into the String Gadget, and select the "Ctrl" Toggle Gadget.
  1126. Under GT/IGRequest, typing the Keyboard Command will have the same effect
  1127. as a GadgetDown and then a GadgetUp Message from the Gadget.
  1128.  
  1129.  
  1130. Requester Key Commands
  1131. To establish requester-wide keyboard commands to end the requester under
  1132. IGRequest or GTRequest use the IG/GTRequest Info Requester.  Currently,
  1133. keyboard commands that do not end the requester, but merely call a
  1134. user-defined function are not supported from within IntuiGen, and there
  1135. have been no special provisions made for them under IG/GTRequest.  The only
  1136. way to implement such commands would be to set up a routine to process
  1137. RawKey or VanillaKey messages and call the appropriate routines on given
  1138. key presses.
  1139.  
  1140. However, if you would like to establish key commands that end the
  1141. requester, in the lower left side of the IG/GTRequest Info requester is a
  1142. group of Gadgets used to set requester-ending keyboard commands.  They work
  1143. similarly to the keyboard command areas of certain Object Information
  1144. Requester (i.e. Button Objects, Image Button Objects, etc.).  Type the
  1145. letter, with no Shift, Alt, Control, or Amiga keys held down, into the
  1146. little String Gadget next to the bank of Toggleselect Gadgets labeled
  1147. "Control," "Alt," "Amiga," and "Shift."  Then, if any special keys are to
  1148. be used with this key to make the keyboard command, select them from the
  1149. bank of Toggleselect Gadgets.  Below these Gadgets are the "End Func:"
  1150. String Gadget and the "FillStruct" Toggleselect Gadget.  When the requester
  1151. is ended by pressing this key, if IGRequest should call a particular
  1152. function, type it into the "End Func:" field.  If IGRequest should fill the
  1153. data structure, select "FillStruct."  If more than one keyboard command is
  1154. to be used to end the requester, click on the down arrow next to the little
  1155. String Gadget containing the ending key.  The ending key Gadgets will all
  1156. be reset, and you can enter new parameters for a second ending key.  Repeat
  1157. this procedure for additional ending keys.  To scroll back through the
  1158. list, use the up arrow key.  You may make changes to any item in the list.
  1159.  
  1160.  
  1161. Object Events
  1162. If, when your requester is running, an Object is clicked on, or the text it
  1163. contains is changed, or the user manipulates it in any way, an event is
  1164. said to have happened to it.  Events usually correspond to IntuiMessages
  1165. relating to the given object.  Under IG/GTRequest, you can specify
  1166. user-defined functions to be called on a given event.  If you see fields
  1167. labeled GUp Func, GDown Func, or DSel Func in any Object Requester, that
  1168. Object can be linked to a user-defined function which will be called on a
  1169. given event.  The "GUp Func:" field contains the name of the function to be
  1170. called by GT/IGRequest when a GadgetUp message is received for this Gadget.
  1171. The "GDown Func:" field contains the name of the function to be called when
  1172. a GadgetDown message is received.
  1173.  
  1174. In the String Gadgets requester is a field labeled "DSel Func."  It is
  1175. nearly identical to "GUp Func:" but will always be called.  GadgetUp
  1176. messages are received from String Gadgets only when the user presses
  1177. Return.  The De-selected Function will be called on any subsequent
  1178. messages.  For instance, if the user uses the mouse to select your String
  1179. Gadget, types something into it, and then clicks on another String Gadget,
  1180. you would not normally receive a GadgetUp message, however, as soon as the
  1181. GadgetDown message is received from the second String Gadget, the
  1182. De-selected Function will be called.  In order for this to work, the String
  1183. Gadget for which you have a De-selected Function needs to have
  1184. "GADGIMMEDIATE" selected as one of its Activation types, and the Window
  1185. needs to be equipped to receive GadgetDown messages.  For this to work
  1186. well, all String Gadgets in the requester need to have "GADGIMMEDIATE"
  1187. selected as an Activation type.
  1188.  
  1189. Under IGRequest, the argument template for calls to user-defined functions are:
  1190.  
  1191.     void Function (struct IGRequest *,struct IntuiMessage *);
  1192.  
  1193. Under GTRequest, the argument template is:
  1194.  
  1195.     void Function (struct GTRequest *,struct IntuiMessage *,
  1196.                   struct GTControl *,struct MessageHandler *);
  1197.  
  1198.  
  1199. IG/GTRequest Info
  1200. To open the IG/GTRequest Info Requester select IG/GTRequest from the menu,
  1201. or type "r."
  1202.  
  1203. The "Struct Name:" field reflects the name to be used for the IG/GTRequest
  1204. structure when generating the code.  The remaining String Gadgets, but for
  1205. the last two in the right bank, reflect the function to be called when a
  1206. IntuiMessage whose class reflects the String Gadget's name is received by
  1207. IG/GTRequest.  If you enter a function name in one of these, when a message
  1208. of the corresponding class is received under IGRequest, your function will
  1209. be called using the following argument template:
  1210.  
  1211.     void Function (struct IGRequest *,struct IntuiMessage *);
  1212.  
  1213. Under GTRequest, the argument template is:
  1214.  
  1215.     void Function (struct GTRequest *,struct IntuiMessage *,
  1216.                   struct GTControl *,struct MessageHandler *);
  1217.  
  1218. The last two String Gadgets in the right bank relate to the data structure
  1219. that IG/GTRequest will fill with data on exit and read data from on
  1220. entrance.  The "Data Struct:" field contains the name of the structure that
  1221. is to be filled by IG/GTRequest. The "Struct Type:" field reflects the type
  1222. of the structure that is to be filled.    Let us use the example from the
  1223. CardFile tutorial, where you have a declaration that reads:
  1224.  
  1225. struct Person {
  1226.     UBYTE Name[100];
  1227.     UBYTE Address[100];
  1228.     UBYTE CityStateZip[100];
  1229.     USHORT Age;
  1230. } People[100];
  1231.  
  1232. In this case, the "Struct Type:" field would contain "Person" and the "Data
  1233. Struct:" field would contain something like "People[1]" or "People[2]."
  1234.  
  1235.  
  1236. Linking To Struct Fields
  1237. To link any Gadgets to a structure field, you must at some point establish
  1238. the type of structure in which the field you are linking to exists.  This
  1239. is done globally in the IG/GTRequest Info Requester.
  1240.  
  1241. To link a String Gadget to a structure field from within IntuiGen is
  1242. simple; in the String Gadgets requester, simply enter the name of the
  1243. structure field from which and to which you want the contents of this
  1244. String Gadget copied.
  1245.  
  1246. Toggle Button Gadgets can also be linked to structure fields, however you
  1247. cannot do this from within IntuiGen.  See the appropriate documentation in
  1248. the IGRequest.guide file and the GTRequest.guide file.
  1249.  
  1250. Most GadTools kinds can be linked to structure fields from within IntuiGen.
  1251. The following table lists each eligible GadTools kind, and the attribute
  1252. which is copied to and from its corresponding structure field.    Following
  1253. the table is an explanation of how to link a GadTools kind to a structure
  1254. field from within IntuiGen.
  1255.  
  1256.     CHECKBOX_KIND    GTCB_Checked
  1257.     MX_KIND     GTMX_Active
  1258.     CYCLE_KIND    GTCY_Active
  1259.     LISTVIEW_KIND    GTLV_Selected
  1260.     PALETTE_KIND    GTPA_Color
  1261.  
  1262. To link one of the above GadTools kinds to a structure field from within
  1263. IntuiGen, open the corresponding Object's requester (see Changing an
  1264. Object).  There will be a field labeled "Field."  Enter the structure
  1265. field's name here.  On the middle left side of the requester will be a
  1266. cycle gadget whose contents default to SHORT.  The options that it cycles
  1267. through correspond to a field type in the GTControl structure.    These
  1268. labels, their corresponding field types, and explanation, is presented
  1269. below.
  1270.  
  1271. SHORT
  1272.     Corresponds to FLD_SHORT
  1273.     The structure field is a signed integral type two bytes wide
  1274. LONG
  1275.     Corresponds to FLD_LONG
  1276.     The structure field is a signed integral type four bytes wide
  1277. FLOAT
  1278.     Corresponds to FLD_FLOAT
  1279.     The structure field is a signed floating point type four bytes wide
  1280.     You must define the GTFLOAT typedef, and the functions
  1281.     StringToFloat and FloatToString in GTRequest.h and recompile
  1282.     GTRequest.c to set this up.  By default GTFLOAT is defined as a ULONG
  1283. BYTE
  1284.     Corresponds to FLD_BYTE
  1285.     The structure field is a signed integral type one byte wide
  1286. POINTER
  1287.     Corresponds to FLD_POINTER The structure field is an unsigned
  1288.     integral type (pointer) four bytes wide This is functionally
  1289.     identical to LONG
  1290. BOOLBIT
  1291.     This corresponds to FLD_BOOLBIT The structure field is an unsigned
  1292.     integral type four bytes wide This causes 1<<control->Bit in the
  1293.     field to be set if control->Attribute is true, otherwise it causes
  1294.     it to be cleared.  It allows for Boolean Bitfield storage.  You
  1295.     must manually set the Bit field in the generated GTControl
  1296.     structure; IntuiGen provides no means to do this. NOTE: This field
  1297.     type is most frequently used when manually linking Toggle buttons
  1298.     to structure fields in the generated code
  1299. ATTRBIT
  1300.     Corresponds to FLD_ATTRBIT
  1301.     Executes the following statement:
  1302.         field= 1<<control->Attribute
  1303.     Not especially useful
  1304. SINSTRUCT
  1305.     Corresponds to FLD_STRINGINSTRUCT
  1306.     if your structure looks like this:
  1307.                     struct mystruct {
  1308.                     type1 field1;
  1309.                     type2 field2;
  1310.                     ...
  1311.                     UBYTE TheField[X];
  1312.                     type3 field4;
  1313.                     type4 field5;
  1314.                     ...
  1315.                     };
  1316.                   Then use this flag to store data as a
  1317.                   string in TheField
  1318. SPINSTRUCT
  1319.     Corresponds to FLD_STRINGPOINTEDTOINSTRUCT
  1320.     if your structure looks like this:
  1321.                   struct mystruct {
  1322.                   type1 field1;
  1323.                   ...
  1324.                   UBYTE *TheField;
  1325.                   typeX FieldX;
  1326.                   ...
  1327.                   };
  1328.                Then use this flag to copy the
  1329.                string to the buffer pointed to
  1330.                by TheField
  1331. STRPTR
  1332.     Corresponds to FLD_STRINGPTR
  1333.     if your structure looks like the one above
  1334.     (for STRINGPOINTEDTOINSTRUCT) and you
  1335.     want to set TheField=control->Attribute
  1336.     (without performing a strcpy)
  1337.     use this.  (Assumes control->Attribute is a
  1338.     char *, functionally identical to FLD_LONG)
  1339.  
  1340.  
  1341.